Overview
This blog post will explain how conferences work in CIC by demonstrating conferencing using an IceLib example application. The example application is only intended to demonstrate the events related to conferencing, not necessarily how to build a custom client that supports conferencing. The application used in this example is published under the Mozilla open source license and is published on GitHub at https://github.com/InteractiveIntelligence/ConferenceExample
Conference Event Summary
A conference will generate the following events, based on the given actions, in this order:
- Action: Place call
- Event: InteractionAdded (first call)
- Action: Place call
- Event: InteractionAdded (second call)
- Action: initiate conference
- Event: InteractionAdded (user's call leg)
- Event: InteractionRemoved (first call)
- Event: InteractionRemoved (first call)
- Event: ConferenceItemAdded (first call)
- Event: InteractionRemoved (second call)
- Event: InteractionRemoved (second call)
- Event: ConferenceItemAdded (second call)
- Action: Disconnect (first call)
- Event: ConferenceItemChanged (first call)
- Action: Disconnect (second call)
- Event: ConferenceItemChanged (second call)
- Event: InteractionChanged (user's call)
- Event: ConferenceItemRemoved (first call)
- Event: ConferenceItemRemoved (second call)
- Event: InteractionRemoved (user's call - deallocation)
Example Application
The example application demonstrates conferencing by providing the ability to log in to CIC, place outbound calls, and conference them together. Referring to the first screenshot below, the application has the following features:
- CIC Authentication - Use a CIC username, CIC password, workstation name, and CIC server name
- Dial Controls - Enter a dialstring in the textbox and click the dial button to the right (handset icon)
- Queue Window - This area displays the interactions on the logged in user's queue (My Interactions)
- Call Controls - Click these buttons to act on the selected interaction
- Output logging - Application messages will be written here. These messages will also be traced to the ININ tracelog for the application.
Conference Walkthrough
This section will show the application at each step in the conference process and will explain the IceLib events.
First call
This screenshot shows the fist call has been placed. The state is connected and the call can be used in a conference (noted by the appearance of the checkbox in the Conference column. Placing a new call will trigger one InteractionAdded event followed by several InteractionChanged events. The changed events are primarily for state changes as the call moves from initializing through the various stages to get to connected.
Second call
This screenshot shows the first and second calls both in queue. Both are available to be added to a conference. The second call generates the same events as the first, but with the new interaction id of the second call.
Pre-conferencing
This screenshot shows both interactions have been selected (checkboxes) to be added to a conference. Because multiple interactions are selected in this way, the call control buttons have been disabled and the Conference button has been enabled because two or more parties have been selected for a conference. Note that the UI updates are all reacting to logic built around various IceLib properties indicating the state and capabilities of the interactions.
Conference created
After clicking the conference button, the selected interactions are placed into conference. The application shows a collapsible record in the queue, which when expanded will show the current conference parties. The checkboxes have been hidden because the interactions are no longer eligible to be added to a conference because they are already in one.
The majority of confusion surrounding conferencing comes from the events directly following the creation of the conference. Consider these traces (changed traces removed for brevity and not important here):
11:49:35_9429218 - [Conference_Executed] -> Making a conference with interactions: 1001465853, 1001465856
11:49:36_0983593 - [QueueOnQueueContentsChanged] -> [1001465859] Interaction Added
11:49:36_1389631 - [QueueOnQueueContentsChanged] -> [1001465853] Interaction Removed
11:49:36_1587596 - [QueueOnQueueContentsChanged] -> [1001465853] Interaction Removed (was not in list)
11:49:36_1627199 - [QueueOnQueueContentsChanged] -> Conference item added: ConferenceId=1001465858, ConferenceItem=1001465853, Interaction=1001465859
11:49:36_1953944 - [QueueOnQueueContentsChanged] -> [1001465856] Interaction Removed
11:49:36_2023278 - [QueueOnQueueContentsChanged] -> [1001465856] Interaction Removed (was not in list)
11:49:36_2072747 - [QueueOnQueueContentsChanged] -> Conference item added: ConferenceId=1001465858, ConferenceItem=1001465856, Interaction=1001465859
The conference is created at the first trace message. The very first thing that happens is that a brand new interaction is added to the user's queue. In the example, this is 1001465859. This new interaction represents the connection of the user (call from station to CIC) and Interaction.IsOnMyInteractionsQueue will be true only for this interaction in the conference.
The next thing that happens in the conference process is that the first interaction provided when creating the conference, 1001465853 in this example, is removed from the user's queue. The removed event is recieved twice (the second one can be ignored). The interaction is then added to the conference. This same sequence of events (two removed, one conference added) happens for each of the remaining items that are to be conferenced.
In any of the conference events (added/changed/removed), the ConferenceId property is the ID for the conference object itself, ConferenceItem is the Interaction to which the event is referring, and Interaction is the Interaction object for "you" in the conference (the Interaction that is on the user's queue.
One interaction disconnected
One of the interactions in the conference has been disconnected and shows with grey text. This raises the conference item changed event for the interaction because its state has changed.
Conference ended
The other interaction in the conference is disconnected and the conference ends. The state description describes the state as Disconnected [Last conference party]. There are two key activities in this stage. First, the "other" interaction in the conference (that is not "you") is disconnected. This triggers the conference item changed event because the conference party has disconnected. CIC then determines that there is only one party remaining in the conference, which is the user's interaction, and disconnects that interaction also. This raises the interaction changed event for the user's interaction because the state changed.
The second action is that because all parties have been disconnected, CIC ends the conference. This triggers the conference item removed event for each party in the conference that is not the user's interaction (because the user's interaction is on the user's queue, and from the user's perspective, is not seen as a conference party).
Conference removed
The user's interaction is deallocated two minutes after the conference has ended and is removed from queue. This raises the interaction removed event, not the conference interaction removed event, because it is removing the user's interaction from their own queue. The conference interaction itself is never on the user's queue (it is on the CIC server or media server) and will therefore not generate a conference event for the user.
Notes About Conferencing
These are some things to consider when dealing with conferencing: